<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />

    <link rel="stylesheet" type="text/css" href="../css/common.css" />
    <link rel="stylesheet" type="text/css" href="../css/screen.css" media="screen" />
    <link rel="stylesheet" type="text/css" href="../css/_print.css" media="print" />
    <link rel="stylesheet" type="text/css" href="../css/prettify.css" media="screen" />

    <title>Chapter 10: JMX Configuration</title>
  </head>
  <body onload="prettyPrint(); decorate();">
    <script type="text/javascript">prefix='../';</script>
    <script type="text/javascript" src="../js/prettify.js"></script>
    <script type="text/javascript" src="../templates/header.js"></script>
    <script type="text/javascript" src="../js/jquery-min.js"></script>
    <script type="text/javascript" src="../js/decorator.js"></script>
    
    <div id="left">
      <noscript>Please turn on Javascript to view this menu</noscript>
      <script src="../templates/left.js" type="text/javascript"></script>
    </div>
    <div id="right">
      <script src="menu.js" type="text/javascript"></script>
    </div>
    <div id="content">
	
    <h1>Chapter 10: JMX Configurator</h1>

    <a href="jmxConfig_ja.html">&#x548C;&#x8A33; (Japanese translation)</a>
    
		<p>As its name indicates, <code>JMXConfigurator</code> allows
		configuration of logback via JMX. In a nutshell, it lets you
		reconfigure logback from the default configuration file, from a
		designated file or URL, list loggers and modify logger levels.
		</p>
		
		<h3>Using the JMX Configurator</h3>
    
    
		<p>If your server run on JDK 1.6 or later, then you can just
		invoke the <code>jconsole</code> application on the command line and
		then connect to your server's MBeanServer. If you are running an
		older JVM, then you should read the section on <a
		href="#jmxEnablingServer">JMX enabling your server</a>.
    </p>

    <p><code>JMXConfigurator</code> is enabled by a single line in
    your logback configuration file, as shown below:
		</p>

    <pre class="prettyprint source">&lt;configuration>
  <b>&lt;jmxConfigurator /></b>
  
  &lt;appender name="console" class="ch.qos.logback.core.ConsoleAppender">
    &lt;layout class="ch.qos.logback.classic.PatternLayout">
      &lt;Pattern>%date [%thread] %-5level %logger{25} - %msg%n&lt;/Pattern>
    &lt;/layout>
  &lt;/appender>

  &lt;root level="debug">
    &lt;appender-ref ref="console" />
  &lt;/root>  
&lt;/configuration></pre>
		
    <p>After you connect to your server with <em>jconsole</em>, on the
    MBeans panel, under "ch.qos.logback.classic.jmx.Configurator"
    folder you should see several operations to choose from, as shown
    in the figure below:
    </p>
    
    <h3 class="doAnchor" name="jmxConfigurator">Screen-shot of
    <code>JMXConfigurator</code> viewed in <code>jconsole</code></h3>

    <img src="images/chapters/jmxConfigurator/jmxConfigurator.gif" alt="jmxConfigurator"/>   

		<p>Thus, you can</p>
		
		<ul>
      <li>Reload logback configuration using the default configuration
      file.</li>

      <li>Reload the configuration with the specified URL.</li>
      <li>Reload the configuration with the specified file.</li>

			<li>Set the level of a specified logger. To set to null, pass
			the string "null" as value.</li>
      <li>Get the level of a specified logger. The returned value can be
      null.</li>
			<li>Get the <a href="architecture.html#effectiveLevel">effective
			level</a> of a specified logger.</li>
		</ul>
		
    <p><code>JMXConfigurator</code> exposes the list of existing
    loggers and a status list as attributes.</p>
    
    <p>The status list can help you diagnose logback's internal
    state.</p>

    <img src="images/chapters/jmxConfigurator/statusList.gif" alt="statusList.gif"/>   

    <h3 class="doAnchor" name="leak">Avoiding memory leaks</h3>

    <p>If your application is deployed in a web-server or an
    application server, the registration of an
    <code>JMXConfigurator</code> instance creates a reference from the
    system class loader into your application which will prevent it
    from being garbage collected when it is stopped or re-deployed,
    resulting in a severe memory leak.</p>

    <p>Thus, unless your application is a standalone Java application,
    you MUST unregister the <code>JMXConfigurator</code> instance from
    the JVM's Mbeans server. Invoking the <code>reset</code>() method
    of the appropriate <code>LoggerContext</code> will automatically
    unregister any JMXConfigurator instance. A good place to reset the
    logger context is in the <code>contextDestroyed</code>()
    method of a
    <code>javax.servlet.ServletContextListener</code>. Here is sample
    code:</p>

    <pre class="prettyprint source">import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;

import org.slf4j.LoggerFactory;
import ch.qos.logback.classic.LoggerContext;

public class MyContextListener implements ServletContextListener {

  public void contextDestroyed(ServletContextEvent sce) {
    <b>LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory();</b>
    <b>lc.stop();</b>
  }

  public void contextInitialized(ServletContextEvent sce) {
  }
} </pre>


    <!-- ============ Multiple web-applications  ================== -->

    
    <h2 class="doAnchor" name="multiple"><code>JMXConfigurator</code>
    with multiple web-applications</h2>

    <p>If you deploy multiple web-applications in the same server,
    and if you have not overridden the default <a
    href="contextSelector.html">context selector</a>, and if you
    have placed a copy of <em>logback-*.jar</em> and
    <em>slf4j-api.jar</em> under the <em>WEB-INF/lib</em> folder of
    each web-application, then by default each <code>JMXConfigurator</code>
    instance will be registered under the same name, that is,
    "ch.qos.logback.classic:Name=default,Type=ch.qos.logback.classic.jmx.JMXConfigurator". In
    other words, by default the various <code>JMXConfigurator</code>
    instances associated with the logger contexts in each of your
    web-applications will collide.
    </p>
    
    <p>To avoid such undesirable collisions, you simply <a
    href="configuration.html#contextName">set the name of your
    application's logging context</a> and <code>JMXConfigurator</code>
    will automatically use the name you have set.
    </p>

    <p>For example, if you deploy two web-applications named "Koala"
    and "Wombat", then you would write in Koala's logback
    configuration
    </p>
    
    <pre class="prettyprint source">&lt;configuration>
  <b>&lt;contextName>Koala&lt;/contextName></b>
  &lt;jmxConfigurator/>
  ...
&lt;configuration></pre>

    <p>and in Wombat logback configuration file, you would write:</p>

    <pre class="prettyprint source">&lt;configuration>
  <b>&lt;contextName>Wombat&lt;/contextName></b>x
  &lt;jmxConfigurator/>
  ...
&lt;configuration></pre>

    <p>In jconsole's MBeans panel, you would see two distinct
    <code>JMXConfigurator</code> instances:</p>

    <img src="images/chapters/jmxConfigurator/multiple.gif" alt="multiple.gif"/>   

    <p>You may fully control the name under which JMXConfigurator is
    registered with an MBeans server with the help of the "objectName"
    attribute of the <code>&lt;jmxConfigurator></code> element.</p>
    
    <!-- ============ JMX enabling your  server ================== -->

    <h3 class="doAnchor" name="jmxEnablingServer">JMX enabling your
    server</h3>

    <p>If your server runs with JDK 1.6 or later, your server should
    be JMX enabled by default.</p>

		<p>For older JVMs, we suggest that you refer to the JMX-related
		documentation of your web-server. Such documentation is available
		for both <a
		href="http://tomcat.apache.org/tomcat-6.0-doc/monitoring.html">Tomcat</a>
		and <a
		href="http://docs.codehaus.org/display/JETTY/JMX">Jetty</a>. In
		this document, we briefly describe the required configuration
		steps for Tomcat and Jetty.
		</p>

    <!-- ================ Configuring Jetty ================== -->

		<h4>Enabling JMX in Jetty (tested under JDK 1.5 and JDK 1.6)</h4>
		
		<p>The following has been tested under JDK 1.5 and 1.6.  Under JDK
		1.6 and later, your server is JMX enabled by default and you can,
		but do not need to, follow the steps discussed below.  Under JDK
		1.5, adding JMX support in Jetty requires a number of additions to
		the <em>$JETTY_HOME/etc/jetty.xml</em> configuration file. Here
		are the elements that need to be added:
		</p>

    <pre class="prettyprint source">&lt;Call id="MBeanServer" class="java.lang.management.ManagementFactory" 
      name="getPlatformMBeanServer"/>

&lt;Get id="Container" name="container">
  &lt;Call name="addEventListener">
    &lt;Arg>
      &lt;New class="org.mortbay.management.MBeanContainer">
        &lt;Arg>&lt;Ref id="MBeanServer"/>&lt;/Arg>
        &lt;Call name="start" />
      &lt;/New>
    &lt;/Arg>
  &lt;/Call>
&lt;/Get> </pre>

    <p>If you wish to access the MBeans exposed by Jetty via the
    <code>jconsole</code> application, then you need to start Jetty after
    having set the "com.sun.management.jmxremote" Java system
    property.
    </p>

    <p>For a standalone version of Jetty, this translates to: </p>

    
    <p class="source">java <b>-Dcom.sun.management.jmxremote</b> -jar start.jar [config files]</p>

    <p>And if you wish to launch Jetty as a Maven plugin, then you
    need to set the "com.sun.management.jmxremote" system property via
    the <code>MAVEN_OPTS</code> shell variable:
    </p>

    <p class="source"><b>MAVEN_OPTS="-Dcom.sun.management.jmxremote</b>"
mvn jetty:run</p>

    <p>You can then access the MBeans exposed by Jetty as well as
    logback's <code>JMXConfigurator</code> via
    <code>jconsole</code>.</p>

    <img src="images/chapters/jmxConfigurator/jconsole15_jetty.gif" alt="jconsole15_jetty.gif"/>   

    <p>After you are connected, you should be able to access
    <code>JMXXConfigurator</code> as shown in the <a
    href="#jmxConfigurator">screenshot</a> above.</p>

    <h4>MX4J with Jetty (tested under JDK 1.5 and 1.6)</h4>

    <p>If you wish to access <code>JMXConfigurator</code> via MX4J's
    HTTP interface and assuming you have already downloaded <a
    href="http://mx4j.sourceforge.net/">MX4J</a>, you then need to
    modify the Jetty configuration file discussed previously by adding
    an instruction to set the management port.
    </p>
    
    <pre class="prettyprint source">&lt;Call id="MBeanServer"
    class="java.lang.management.ManagementFactory"
    name="getPlatformMBeanServer"/>

&lt;Get id="Container" name="container">
  &lt;Call name="addEventListener">
    &lt;Arg>
      &lt;New class="org.mortbay.management.MBeanContainer">
        &lt;Arg>&lt;Ref id="MBeanServer"/>&lt;/Arg>
        <b>&lt;Set name="managementPort">8082&lt;/Set></b>
        &lt;Call name="start" />
      &lt;/New>
    &lt;/Arg>
  &lt;/Call>
&lt;/Get> 
    </pre>
    
    <p>Moreover, <em>mx4j-tools.jar</em> needs to be added to Jetty's
    class path.
    </p>

    <p>If you are running Jetty as a Maven plug-in, then you need to add
    <em>mx4j-tools</em> as a dependency.</p>

    <pre class="prettyprint source">&lt;plugin>
  &lt;groupId>org.mortbay.jetty&lt;/groupId>
  &lt;artifactId>maven-jetty-plugin&lt;/artifactId>
  &lt;configuration>
    &lt;jettyConfig>path/to/jetty.xml&lt;/jettyConfig>
    ...
  &lt;/configuration>
  <b>&lt;dependencies>
    &lt;dependency>
      &lt;groupId>mx4j&lt;/groupId>
      &lt;artifactId>mx4j-tools&lt;/artifactId>
      &lt;version>3.0.1&lt;/version>
    &lt;/dependency>
  &lt;/dependencies></b>
&lt;/plugin></pre>

		<p>After Jetty is started with the above configuration,
		<code>JMXConfigurator</code> will be available at the following
		URL (search for "ch.qos.logback.classic"):
		</p>

    <p class="source"><a href="http://localhost:8082/">http://localhost:8082/</a></p>

    <p>Below is a screen shot view of the MX4J interface.</p>

    <img src="images/chapters/jmxConfigurator/mx4j_jetty.gif" alt="mx4j_jetty.gif"/>   


    <!-- ================ Tomcat ================== -->
		
		<h4>Configuring JMX for Tomcat (tested under JDK 1.5 and 1.6)</h4>
    
    <p>If you are using JDK 1.6 and later, your server is already JMX
    enabled by default and you can, but do not need to, follow the
    steps discussed below. Under JDK 1.5, Tomcat requires the addition
    of the following lines to the
    <em>$TOMCAT_HOME/bin/catalina.bat/sh</em> shell script:
		</p>
		
    <p class="source">CATALINA_OPTS="-Dcom.sun.management.jmxremote"</p>

		<p>Once started with these options, MBeans exposed by Tomcat as
		well logback's <code>JMXConfigurator</code> can be accessed with
		<code>jconsole</code> by issuing the following command in a shell:
		</p>
    
    <p class="source">jconsole</p>

    <img src="images/chapters/jmxConfigurator/jconsole15_tomcat.gif" alt="jconsole15_tomcat.gif"/>   

    <p>After you are connected, you should be able to access
    <code>JMXXConfigurator</code> as shown in the <a
    href="#jmxConfigurator">screenshot</a> above.</p>


    <h4>MX4J with Tomcat (tested under JDK 1.5 and 1.6)</h4>
    
		<p>You might prefer to access JMX components via a web-based
		interface provided by MX4J.  In that case, here are the required
		steps:
		</p>
		
    <p>Assuming you have already downloaded <a
    href="http://mx4j.sourceforge.net/">MX4J</a>, place the
    <em>mx4j-tools.jar</em> file under the <em>$TOMCAT_HOME/bin/</em>
    directory. Then, add the following lines to the
    <em>$TOMCAT_HOME/bin/catalina.sh</em> configuration file:
		</p>

    <p class="source">&lt;!-- at the beginning of the file -->
CATALINA_OPTS="-Dcom.sun.management.jmxremote"

&lt;!-- in the "Add on extra jar files to CLASSPATH" section -->
CLASSPATH="$CLASSPATH":"$CATALINA_HOME"/bin/mx4j-tools.jar</p>

		<p>Finally, declare a new <code>Connector</code> in the
		<em>$TOMCAT_HOME/conf/server.xml</em> file:
		</p>

		
    <pre class="prettyprint source">&lt;Connector port="0" 
  handler.list="mx"
  mx.enabled="true" 
  mx.httpHost="localhost" 
  mx.httpPort="8082" 
  protocol="AJP/1.3" /></pre>
  
  	<p>Once Tomcat is started, you should be able to find
  	JMXConfigurator by pointing your browser at the following URL
  	(search for "ch.qos.logback.classic"):
  	</p>

    <p class="source"><a href="http://localhost:8082">http://localhost:8082/</a></p>

    <p>Below is a screen shot view of the MX4J interface.</p>

    <img src="images/chapters/jmxConfigurator/mx4j_tomcat.gif" alt="mx4j_tomcat.gif"/>   

		
	
	
    <script src="../templates/footer.js" type="text/javascript"></script>
  </div>
</body>
</html>
